Add script 'release/update-manpages' to generate manpages Debian package started to ship manpages for repo since 2.8 [1] And it's about for one year. So I think it should be upstreamed. The script depends on help2man, which is available in both debian [2] and ubuntu [3]. [1] https://tracker.debian.org/news/1150858/accepted-repo-28-1-source-into-unstable [2] https://tracker.debian.org/pkg/help2man [3] https://launchpad.net/ubuntu/+source/help2man Change-Id: Ide2b356d0944ebde34cc96c6d5a782655bd72288 Signed-off-by: Roger Shimizu <rosh@debian.org> Reviewed-on: https://gerrit-review.googlesource.com/c/git-repo/+/309782 Reviewed-by: Mike Frysinger <vapier@google.com>
diff --git a/man/repo-sync.1 b/man/repo-sync.1 new file mode 100644 index 0000000..70f7c20 --- /dev/null +++ b/man/repo-sync.1
@@ -0,0 +1,208 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man. +.TH REPO "1" "July 2021" "repo sync" "Repo Manual" +.SH NAME +repo \- repo sync - manual page for repo sync +.SH SYNOPSIS +.B repo +\fI\,sync \/\fR[\fI\,<project>\/\fR...] +.SH DESCRIPTION +Summary +.PP +Update working tree to the latest revision +.SH OPTIONS +.TP +\fB\-h\fR, \fB\-\-help\fR +show this help message and exit +.TP +\fB\-j\fR JOBS, \fB\-\-jobs\fR=\fI\,JOBS\/\fR +number of jobs to run in parallel (default: 1) +.TP +\fB\-\-jobs\-network\fR=\fI\,JOBS\/\fR +number of network jobs to run in parallel (defaults to +\fB\-\-jobs\fR) +.TP +\fB\-\-jobs\-checkout\fR=\fI\,JOBS\/\fR +number of local checkout jobs to run in parallel +(defaults to \fB\-\-jobs\fR) +.TP +\fB\-f\fR, \fB\-\-force\-broken\fR +obsolete option (to be deleted in the future) +.TP +\fB\-\-fail\-fast\fR +stop syncing after first error is hit +.TP +\fB\-\-force\-sync\fR +overwrite an existing git directory if it needs to +point to a different object directory. WARNING: this +may cause loss of data +.TP +\fB\-\-force\-remove\-dirty\fR +force remove projects with uncommitted modifications +if projects no longer exist in the manifest. WARNING: +this may cause loss of data +.TP +\fB\-l\fR, \fB\-\-local\-only\fR +only update working tree, don't fetch +.TP +\fB\-\-no\-manifest\-update\fR, \fB\-\-nmu\fR +use the existing manifest checkout as\-is. (do not +update to the latest revision) +.TP +\fB\-n\fR, \fB\-\-network\-only\fR +fetch only, don't update working tree +.TP +\fB\-d\fR, \fB\-\-detach\fR +detach projects back to manifest revision +.TP +\fB\-c\fR, \fB\-\-current\-branch\fR +fetch only current branch from server +.TP +\fB\-\-no\-current\-branch\fR +fetch all branches from server +.TP +\fB\-m\fR NAME.xml, \fB\-\-manifest\-name\fR=\fI\,NAME\/\fR.xml +temporary manifest to use for this sync +.TP +\fB\-\-clone\-bundle\fR +enable use of \fI\,/clone.bundle\/\fP on HTTP/HTTPS +.TP +\fB\-\-no\-clone\-bundle\fR +disable use of \fI\,/clone.bundle\/\fP on HTTP/HTTPS +.TP +\fB\-u\fR MANIFEST_SERVER_USERNAME, \fB\-\-manifest\-server\-username\fR=\fI\,MANIFEST_SERVER_USERNAME\/\fR +username to authenticate with the manifest server +.TP +\fB\-p\fR MANIFEST_SERVER_PASSWORD, \fB\-\-manifest\-server\-password\fR=\fI\,MANIFEST_SERVER_PASSWORD\/\fR +password to authenticate with the manifest server +.TP +\fB\-\-fetch\-submodules\fR +fetch submodules from server +.TP +\fB\-\-use\-superproject\fR +use the manifest superproject to sync projects +.TP +\fB\-\-no\-use\-superproject\fR +disable use of manifest superprojects +.TP +\fB\-\-tags\fR +fetch tags +.TP +\fB\-\-no\-tags\fR +don't fetch tags +.TP +\fB\-\-optimized\-fetch\fR +only fetch projects fixed to sha1 if revision does not +exist locally +.TP +\fB\-\-retry\-fetches\fR=\fI\,RETRY_FETCHES\/\fR +number of times to retry fetches on transient errors +.TP +\fB\-\-prune\fR +delete refs that no longer exist on the remote +.TP +\fB\-s\fR, \fB\-\-smart\-sync\fR +smart sync using manifest from the latest known good +build +.TP +\fB\-t\fR SMART_TAG, \fB\-\-smart\-tag\fR=\fI\,SMART_TAG\/\fR +smart sync using manifest from a known tag +.SS Logging options: +.TP +\fB\-v\fR, \fB\-\-verbose\fR +show all output +.TP +\fB\-q\fR, \fB\-\-quiet\fR +only show errors +.SS repo Version options: +.TP +\fB\-\-no\-repo\-verify\fR +do not verify repo source code +.PP +Run `repo help sync` to view the detailed manual. +.SH DETAILS +.PP +The 'repo sync' command synchronizes local project directories with the remote +repositories specified in the manifest. If a local project does not yet exist, +it will clone a new local directory from the remote repository and set up +tracking branches as specified in the manifest. If the local project already +exists, 'repo sync' will update the remote branches and rebase any new local +changes on top of the new remote changes. +.PP +\&'repo sync' will synchronize all projects listed at the command line. Projects +can be specified either by name, or by a relative or absolute path to the +project's local directory. If no projects are specified, 'repo sync' will +synchronize all projects listed in the manifest. +.PP +The \fB\-d\fR/\-\-detach option can be used to switch specified projects back to the +manifest revision. This option is especially helpful if the project is currently +on a topic branch, but the manifest revision is temporarily needed. +.PP +The \fB\-s\fR/\-\-smart\-sync option can be used to sync to a known good build as +specified by the manifest\-server element in the current manifest. The +\fB\-t\fR/\-\-smart\-tag option is similar and allows you to specify a custom tag/label. +.PP +The \fB\-u\fR/\-\-manifest\-server\-username and \fB\-p\fR/\-\-manifest\-server\-password options can +be used to specify a username and password to authenticate with the manifest +server when using the \fB\-s\fR or \fB\-t\fR option. +.PP +If \fB\-u\fR and \fB\-p\fR are not specified when using the \fB\-s\fR or \fB\-t\fR option, 'repo sync' will +attempt to read authentication credentials for the manifest server from the +user's .netrc file. +.PP +\&'repo sync' will not use authentication credentials from \fB\-u\fR/\-p or .netrc if the +manifest server specified in the manifest file already includes credentials. +.PP +By default, all projects will be synced. The \fB\-\-fail\-fast\fR option can be used to +halt syncing as soon as possible when the first project fails to sync. +.PP +The \fB\-\-force\-sync\fR option can be used to overwrite existing git directories if +they have previously been linked to a different object directory. WARNING: This +may cause data to be lost since refs may be removed when overwriting. +.PP +The \fB\-\-force\-remove\-dirty\fR option can be used to remove previously used projects +with uncommitted changes. WARNING: This may cause data to be lost since +uncommitted changes may be removed with projects that no longer exist in the +manifest. +.PP +The \fB\-\-no\-clone\-bundle\fR option disables any attempt to use \fI\,$URL/clone.bundle\/\fP to +bootstrap a new Git repository from a resumeable bundle file on a content +delivery network. This may be necessary if there are problems with the local +Python HTTP client or proxy configuration, but the Git binary works. +.PP +The \fB\-\-fetch\-submodules\fR option enables fetching Git submodules of a project from +server. +.PP +The \fB\-c\fR/\-\-current\-branch option can be used to only fetch objects that are on the +branch specified by a project's revision. +.PP +The \fB\-\-optimized\-fetch\fR option can be used to only fetch projects that are fixed +to a sha1 revision if the sha1 revision does not already exist locally. +.PP +The \fB\-\-prune\fR option can be used to remove any refs that no longer exist on the +remote. +.PP +SSH Connections +.PP +If at least one project remote URL uses an SSH connection (ssh://, git+ssh://, +or user@host:path syntax) repo will automatically enable the SSH ControlMaster +option when connecting to that host. This feature permits other projects in the +same 'repo sync' session to reuse the same SSH tunnel, saving connection setup +overheads. +.PP +To disable this behavior on UNIX platforms, set the GIT_SSH environment variable +to 'ssh'. For example: +.IP +export GIT_SSH=ssh +repo sync +.PP +Compatibility +.PP +This feature is automatically disabled on Windows, due to the lack of UNIX +domain socket support. +.PP +This feature is not compatible with url.insteadof rewrites in the user's +~/.gitconfig. 'repo sync' is currently not able to perform the rewrite early +enough to establish the ControlMaster tunnel. +.PP +If the remote SSH daemon is Gerrit Code Review, version 2.0.10 or later is +required to fix a server side protocol bug.
